Skip to main content

CogSol Framework

CogSol Framework is a lightweight, agent-first Python framework for building, managing, and deploying AI assistants. It provides scaffolding, agent abstractions, and file-based migration utilities for CogSol projects without requiring an external database.

Overview​

CogSol is designed to provide a Django-like development experience for building AI agents. It uses a code-first approach where you define your agents, tools, and configurations in Python, then use migrations to sync with a remote CogSol API.

Design Philosophy​

  • Code-First: Define agents and tools as Python classes
  • Migration-Based Deployments: Track changes via migrations (similar to Django)
  • No Database Required: Uses JSON files for state tracking
  • API-Synchronized: Push local definitions to remote CogSol APIs

Key Features​

FeatureDescription
Agent DefinitionsDefine AI agents as Python classes with configurable attributes
Tool SystemCreate reusable tools with typed parameters and decorators
Topics & DocumentsOrganize knowledge bases with hierarchical topics and document ingestion
RetrievalsConfigure semantic search across your document collections
MigrationsTrack and version agent/tool/topic changes
Remote SyncPush definitions to CogSol Cognitive and Content APIs
Interactive ChatBuilt-in CLI for testing agents
Import/ExportImport existing assistants from the API

Get Started​

1. Installation​

From Source

git clone https://github.com/cogsol/cogsol-framework cogsol-framework
cd cogsol-framework
pip install -e .

Using PyPI

pip install cogsol-framework

Requirements

  • Python 3.9+

After installation, the cogsol-admin command becomes available globally.

2. Configure Environment​

Set your CogSol API credentials in the .env file:

COGSOL_ENV=development
COGSOL_API_KEY=your-api-key
# Optional: Azure AD B2C client credentials for JWT
# If not provided, the Auth will be skipped
COGSOL_AUTH_CLIENT_ID=your-client-id
COGSOL_AUTH_SECRET=your-client-secret

3. Configure API key of your preferred LLM provider​

To run your agents, you’ll need to configure first the API key of your preferred LLM provider:

  • OpenAI
  • Google Gemini
  • Anthropic

You can add your API key at Cogsol platform

CogSol Cookbook

CogSol Cookbook is a reporitory with templates and runnable demos for building with the CogSol Framework.

In the repository you will find:

  • templates/ contains reusable starter projects.
  • examples/ contains specific demos, often more complete and complex than templates.